<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<meta content="text/html; charset=UTF-8" http-equiv="content-type" />
		<title>Webappkit 0.9</title>
		<link rel="stylesheet" type="text/css" href="static/css/webappkit.web.css" media="screen" />
	</head>
	<body>
		<div id="header">
			<h1><span>WebAppKit</span></h1>
			<p class="baseline">Build web apps the way you want it.</p>
		</div>
		<div id="content">
			<div class="main">
				<p>Welcome to your webappkit root folder. Installed version is <em>alpha</em> 0.9</p>
				<p>Later on, this place will provide a full web administration interface.
				Currently, it's a static pages trying to provide some useful informations.</p>
				
				<h2 id="using-a-kit">Using a Kit</h2>
				<p>Unzip webappkit at the root of your web application. 
				It's probably done as the file you're reading is part of it. 
				It creates a webappkit/ folder. Before retrieving any Kit, put this line into your code :</p>
				<code>/**
* getting webappkit core (only once call is necessary)
*/
include('webappkit/include-me.php');</code>
				<p>When you need a Kit's resources, let's say <em>ooxmlrpc</em>, <strong>load it</strong> with :</p>
				<code>/**
* loads a kit resources
*/
webappkit::getKit('ooxmlrpc');</code>
				<p>If you need only a subkit, let's say <em>http</em> within <em>databeans</em>, get it with :</p>
				<code>/**
* loads a subkit's resources
*/
webappkit::getKit('databeans/http');</code>
				<p>In this exemple, <em>databeans/http</em> requires <em>databeans/databean</em>, but you don't have to take care about that.</p>

				<p>webappkit::getkit($id) returns the kit instance. Always use this method to retrieve a kit, as Kits should be singletons.</p>

				<h2 id="tools">Tools</h2>
				<p><em>Tools</em> are named object instances taking their configuration data from the kit they belong to.</p>
				<p>They are retrieved as kit members like this :</p>
				<code>/**
 * retrieving the kit instance.
 */
$kit=&webappkit::getKit('helloworld');
/**
 * calling the method "bar" of the kit's tool named "foo"
 */
$kit->foo->bar();</code>

				<h2 id="storages">Storages</h2>
				<p><em>Storages</em> are specific Tools. They build and retrieve object instances stored within kits files.</p>
				<p>You use them just as any other Tool, as a kit's member. For example, let's get a template from our sample kit :</p>
				<code>/**
 * retrieving the kit instance.
 */
$kit=&webappkit::getKit('helloworld');
/**
 * getting the template from the storage, which is named "templates"
 */
$tpl=$kit->templates->getItem('help');
/**
* using the 
*/
echo $tpl->render();</code>

				<!-- builders help -->
				<h2 id="building-a-kit">Building a Kit</h2>
				<p>Let's build a Kit named <em>mykit</em>, which will contain a couple of class definition files.
				<ol>
					<li>
						<p>Create a folder named <strong>mykit.wak</strong> within your <em>webappkit/</em> folder.</p>
					</li>
					<li>
						<p>Put your code files inside, let's say <strong>myclass.class.php</strong> and <strong>mychildclass.class.php</strong> which is extending it.</p>
					</li>
					<li>
						<p>Create an INI file at its root named <strong>wak.ini</strong> and edit it :</p>
						<code>[kit]
; kit-wide meta informations
version = "0.1"
; kit version. Will be used later.
desc = "This is my first kit. It will rocks !"
; a short description. Single line to be INI compliant !
phpversion = "4.3-5.*"
; define which PHP versions range compatibility (optional)
; you can use a single version string with jokers, as 4.*

[load_kits]
; kits to load before self resources, order will be preserved.
; n = "absolute kit id"
0 = "datapath"

[load_files]
; self resources to load, order will be preserved.
; n = "relative/path/to/file"
0 = "myclass.class.php"
1 = "mychildclass.class.php"
</code>
						<p>This file describe Kit's resources and dependancies.
						Kits and files will be loaded in the order you defined.</p>
					</li>
				</ol>
				<p>Here we're done with the main kit.</p>
				<p>Please note that Kits are singletons and won't be instanciated twice. Hopefully.</p>
			
			<h3>PHP version auto-switch</h3>
			<p>You can have a library file for each PHP versions, and tell the kit to load the appropriate one upon the current PHP version running.</p>
			<p>To do this, we will name our files with the specific extensions : .php4 and .php5 , and then edit the kit's INI as this :</p>
			<code>[load_files]
; self resources to load, order will be preserved.
; n = "relative/path/to/file"
0 = "myclass.class.php*"
1 = "mychildclass.class.php*"
</code>
			<p>Using * at the end of the file name will trigger the load of .php4 or .php5, upon the current running PHP version.</p>

			<h2 id="building-a-subkit">Building a subkit</h2>
				<p>Kits can contain subkits, which can be either optional or loaded by their parent kit.</p>
				<p>It will also require another kit, <em>webappkit/datapath</em>, and provide an extension as an optional subkit named <em>mysubkit</em>.</p>
				<ol>
					<li>
						<p>Into <em>mykit.wak/</em>, create a folder named <strong>mysubkit.wak</strong></p>
					</li>
					<li>
						<p>Put its own code files into it, for example <strong>anotherclass.php4</strong> and <strong>anotherclass.php5</strong>, which are PHP4 and PHP5 versions of the same class as seen before.</p>
					</li>
					<li>
						<p>Create its <strong>wak.ini</strong> file at its root :</p>
						<code>[load_kits]
; kits to load before self resources, order will be preserved.
; n = "absolute kit id"
0 = "mykit"
1 = "pathnodes"

[load_files]
; self resources to load, order will be preserved.
; n = "relative/path/to/file"
0 = "anotherclass.php*"</code>
						<p>As you see, this subkit requires its parent kit and another kit, <em>pathnodes</em>.
						It also requires <em>datapath</em>, but this dependancy is already defined by parent kit.</p>
						
					</li>
				</ol>
				<p>A subkit may contain itself a subkit and so on.</p>
				<h3>Subkits auto-loading</h3>
				<p>If we want the parent kit <em>mykit</em> to load its subkit when loaded itself, we can add this into <em>mykit</em>'s wak.ini file :</p>
				<code>[load_subkits]
; subkits to load after self resources, order will be preserved
; n = "relative subkit id"
0 = "mysubkit"</code>
				<p>The subkit will be loaded <strong>after</strong> paren'ts kit dependancies and own files.</p>

				<h2 id="adding-tools">Adding Tools</h2>
				<p>Tools have to be declared within kit's <em>wak.ini</em> file :</p>
				<code>[load_files]
0 = "worker.class.php"

[tools]
; name = "class"
bob = "worker"</code>
				<p>Here we have declared a tool wich will be named <em>bob</em> within the kit and will be an instance of the class <em>worker</em>.</p>
				<p>Tools classes have to extends <em>wakTool</em> class.
				Their definition file can be included within the providing kit or one of its dependencies.
				Here it's an included one. Let's look at its class definition :</p>
				<code>class worker extends wakTool {
	/**
	* a Factory function : every Tool has to declare it
	* @static
	* @param string $kit kit's id
	* @param string $name tool's name within kit
	* @return object worker's instance
	*/
	function & factory($kit,$name) {
		return new worker($kit,$name);
	}
	
	/**
	* here is an useful function
	* @return string hairs color
	*/
	function getHairs() {
		return $this->cfg['hairs'];
	}
	
	/**
	* @var array the default configuration values
	*/
	var $cfg=array('hairs'=>'red');
}</code>
				<p>Now, we can get tool <em>bob</em> from our kit and it will have its default config :</p>
				<code>$kit=&webappkit::getkit('mykit');
/**
* this will print 'red'
*/
echo $kit->bob->getHairs();</code>
				
				<h3>Borrowing tools</h3>
				<p>But our <em>worker</em> class can now be used in another kit, by declaring it in the kit's <em>wak.ini</em> file :</p>
				<code>[kit]
desc = "this is another kit, providing a worker tool borrowed from mykit"

[load_kits]
0 = "mykit"
; we need its "worker" class for alice service

[tools]
alice = "worker"</code>
				<p>And let's override its config. Create a file named <strong>alice.tool.ini</strong> at the <em>anotherkit</em>'s root :</p>
				<code>; this is the alice tool config file for anotherkit
hairs = "blue"</code>
				<p>Let's look at our second tool instance :</p>
				<code>$kit2=webappkit::getkit('anotherkit');
/**
 * this will print "blue"
 */
echo $kit2->alice->getHairs();</code>
				<p>And you can also have several instances of the same tool within the same kit, each with its own config.</p>

				<h2 id="adding-storages">Adding storages</h2>
				<p>Storages are just specific tools.
				Just like them, their definition file can be included within their providing kit, or they can just provide a config file for a tool class taken from an external kit dependancy.</p>
				<p>They have to extend <strong>wakStorage</strong> class, which is provided by <strong>webappkit/storages</strong> kit.</p>
				<p>Their function is to retrieve object instances stored in files within the kit.</p>
				<p>Here we will get templates from our kit, using a storage class provided by <em>djtpl</em> template engine kit.</p>
				<p>Here's our kit's <em>wak.ini</em> :</p>
				<code>[load_kits]
; getting dependancies, including the storage class
0 = "djtpl"
; please note that djtpl kit itself require webappkit/storages

[tools]
; declaring storage, name = "class"
templates = "djtplstorage"</code>
				<p>And now we override some storage config in <em>templates.tool.ini</em> :</p>
				<code>; this is the templates storage config
search = "views/{{lang}}/{{id}}.{{type}}"
; here is the filename template for files search
[critera]
; the defaults values for search criteria
lang = "en"
type = "html"</code>
				</p>This settings indicate that template files will be stored within a <em>views/</em> folder within our kit,
				having languages subfolders, and that files are named by id.type.
				The default language is set to <em>en</em>, and default type to <em>html</em>.</p>
				<p>Now, let's get a template from our kit.
				First, we will change the language default value to <em>fr</em>.
				Then, we want the template having the <em>home</em> id.</p>
				<code>/**
 * changing a criteria's default value
 */
$kit->templates->setCriteria('lang','fr');
/**
 * getting a template
 * string criteria will be taken as 'id'
 * or you can provide an associative array for more criteria
 * missing criteria will be taken from current defaults
 * this will build a template instance from views/fr/home.html
 */
$tpl=$kit->templates->getItem('home');
/**
* rendering the template
*/
echo $tpl->render();</code>

			</div>
			<div class="sub">
				<h3>Getting Started</h3>
				<ul class="nav">
					<li><a href="#overview">Overview</a></li>
					<li>
						<a href="#using-a-kit">Using a Kit</a> :
						<a href="#using-tools">Tools</a>,
						<a href="#using-storages">Storages</a>
					</li>
					<li>
						<a href="#building-a-kit">Building a Kit</a>,
						<a href="#building-a-subkit">Building a subkit</a>
					</li>
					<li>
						<a href="#adding-tools">Adding Tools</a>,
						<a href="#adding-storages">Adding Storages</a>
					</li>
				</ul>
			
				<h3>Links</h3>
				<ul class="nav">
					<li><a href="http://webappkit.net">Project home</a>
					<li>Read the <a href="http://blog.webappkit.net" hreflang="en">blog</a> for last news.</li>
				<li>Read the <a href="http://code.google.com/p/webappkit/w/list" hreflang="en">wiki</a> for concepts.</li>
					<li>Read the <a href="http://code.webappkit.net" hreflang="en">core kit documentation</a>.</li>
				</ul>
				
				<h3>Provided Kits</h3>
				<dl>
					<dt>webappkit/storages</dt>
					<dd>wakStorage tool class.</dd>
					<dt>ooxmlrpc</dt>
					<dd>An object_oriented XML-RPC library</dd>
					<dt>xpathdoc</dt>
					<dd>Access XML document as objects, with XPath syntax</dd>
					<dt>databeans</dt>
					<dd>Data structures with auto-validation and formatting. Includes http, datetime, sqlrecord subkits.</dd>
					<dt>datapath</dt>
					<dd>Access tree data structures (arrays and objects) with a dot syntax.</dd>
					<dt>djtpl</dt>
					<dd><a href="http://djangoproject.com">Django</a> template engine partial implementation.</dd>
					<dt>pathnodes</dt>
					<dd>Filesystem elements as objects. Includes common, ini, w3clog, yaml, od (for opendocument) subkits.</dd>
				</dl>
			</div>
		</div>
	</body>
</html>
